AGA Toolkit '97

home *** CD-ROM | disk | FTP | other *** search

/ AGA Toolkit '97 / The AGA Toolkit '97.iso / text / misc / port / port.guide.text < prev next >

Wrap

Text File | 1996-09-07 | 18.2 KB | 453 lines

MAIN Port Copyright © 1993-1994 Henrik Tikanvaara All rights reserved Index ~~~~~ Copyright Copyright, distribution terms and contact address. Introduction Introduction to Port. Instructions General instructions. Usage Commandline usage and options. Preferences Port preferences file. Misc stuff Other notes. History History of changes. Finally Some final words. Other prods Information about other things I've coded. copyright This program is freeware, you may copy it on as long as there is no charge for the program (except for small handling fees if this program is distributed on a disk), and all of the files accompanying Port and Port itself are unaltered and remain intact. If you desire to put Port on a CD-ROM or in some other kind of PD-Shareware library, please contact me. The author accepts no responsibility whatsoever regarding Port, or anything else for that matter. All donations will be gladly accepted, though checks and foreign currencies all have the problem with the banks charging monstrous fees to convert the money to Finnish marks. So don't send 'em, you'll be wasting your money. Finnish marks and US dollars are most welcome, as are also letters, chocolate, beer, disks, hardware etc. Sending something along a suggestion will have a very positive effect on its chances being done. =) Contact addresses: Mail: Henrik Tikanvaara Tikasrinne 3A 02200 Espoo Finland Internet: In order of preference, only use the latter ones if you get no reply in 2 weeks. I check my email once a week. shadowlord@brahman.nullnet.fi sl@field.ichaos.nullnet.fi henrik.tikanvaara@mpoli.fi intro Have you ever got a textfile which had fine ASCII characters, but the accented characters were all wrong, and the file had a ^M after each line? You had probably found a textfile written on PC. Port translates the PC characters to their Amiga equivalents, or at least tries to make a very close match. It also knows how to translate a SF7 format textfile. More than this though, you can perform many other useful functions to textfiles, I really advise you take the time to get familiar with the different functions. Port can be viewed as a utility similar to a GFX converter, with the difference that it works on textfiles. instructions Port can only be run from the Shell, other than that, it should be very easy to use. Everything in the commandline is case-sensitive. The commandline is organized much like in LhA. First the options which are always prefaced by a dash, then the mode, and lastly the input and output filenames. The output filename is optional. Check Usage for a fast index of all different options. usage Port V2.00 Copyright © 1994 Henrik Tikanvaara Usage: Port [Options] <Mode> <Source> [Dest] Mode Options s SF7->Amiga -a ANSI strip p PC ->Amiga -b No conversion buffer c Combined -e# Make EOLs S Amiga->SF7 -i# InterNet strip (1-Note/2-Blank) P Amiga->PC -l LhA pack output file l Lowercase -n No endspace removal u Uppercase -p PowerPack output file o Only ASCII -s# Spaces to tabs (Def 8) n Null -t# Tabs to spaces (Def 8) -? Credits Source The source filename to be converted. Dest The optional filename for the converted text. combined "c" Combined Decodes PC and SF7 characters to Amiga format. Useful for textfiles which have used the SF7 character set with the PC graphics characters etc. prefs Port has a preferences file, where you can specify options that you want to be active or inactive on every conversion. If you want to override the preferences options, it can be done by setting the option in the commandline, with an exclamation mark following it. For example, if you have spaces to tabs conversion on (-s), and you want to turn it off, write "-s!". After you have modified the options file to your preference, you must copy it to "ENV:" and "ENVARC:". If you are about to have conflicting options, you must first turn off the option you don't want, and then specify the other option. For example, you have specified SpacesToTabs conversion in the preferences, but now you want to use TabsToSpaces option. These options normally cause a conflict. In the commandline, first you have to write "-s!" (Suppress SpacesToTabs) and only after that you can specify "-t" (TabsToSpaces). The following options can be specified in the preferences file: ANSIStrip ConversionBuffer EndSpaceRemoval InterNetStrip LhAPack MakeEOLs PowerPackOutput SpacesToTabs TabsToSpaces TempDir TickDelay ansistrip Strips all ANSI codes from the file. Both $1B,"[" and $9B are understood as the CSI or Control Sequence Introducer. instrip Strips InterNet message headers from the textfile. If "1" is specified as the option, a text telling that a header was removed is inserted to each place where this was done. For "2", no text is inserted, the header is simply cut off. This is done in the following way: The input lines are scanned for starting with "From " or "Path: ". If the found text is "Path: ", then all the following lines are cut off, until an empty line is encountered. If the text is "From ", the line is also scanned for numbers and colons, which should be present if the line has a time stamp. If those conditions were fulfilled, the data is skipped until hitting an empty line. For the "From " part, this method should work pretty well, but the cut might accidentally be triggered if a normal line starts with "Path: ". Use with care. lhaoutput The output textfile is automatically packed with LhA. For this to work you have to have LhA in your path. ppoutput The output textfile is automatically packed using "powerpacker.library", with best compression and largest buffer size. tempdir Specifies where the temporary output textfile is written when a packing option is selected. You should use a directory in RAM: but if you run out of memory, you can set it somewhere else. tickdelay Specifies the delay between each progress report. Actually, it specifies the number of Vertical Blanks to wait before printing a new progress report. For normal PAL monitors, there are 50 VBlanks in a second, so setting this to 25 will result in 2 progress reports per second, 10 in 5 and so on. NTSC monitors have 60 per second, and multisync have something like 70, I think. On my Amiga 1200 with fast RAM, I noticed that it doesn't affect the conversion speed by much on values at and over 15 VBlanks (with a monitor of 50 VBlanks per sec). A value between 15-50 is usually good for PAL systems. Setting the option off specifies 1 progress report per second. opt_noconvbuf "-b" No conversion buffer By default, Port reads the whole source file in memory and then converts and writes at the same time. But in case you're short of memory, this option makes Port read and write at the same time. This mode uses memory based on how much you have left, but with the lower limit of 100kB. Especially to floppy users with very little memory: use two different devices with this, if you don't want the conversion to be unreasonably slow. Some options don't work while this option is active. makeeols "-e#" Make EOLs Turns a string of at least # spaces into a linefeed. This option is useful if you saved a writer-routine's data from a demo or an intro in a textfile. Usually the text has no linefeeds, only some 10 spaces or so between each of the "lines". This way you can make the file much more readable. # can be 1-99. endspace "-n" No endspace removal By default Port removes all spaces and tabs that precede the end of the line. These are usually invisible to the user, and are left by the writer of the textfile by accident. Removing them shouldn't cause any harm, but it will reduce the size of the file. In case you need the spaces or tabs in the ends of the lines, use this option. spacestotabs "-s#" Spaces to tabs Tells Port to convert any strings of spaces and tabs to tabs, using # as the tabsize, in case it reduces the size of the textfile. # can be from 1 to 16. Without size specification, 8 will be used. This option is very useful with charts and other textfiles with lots of spaces in them, because they get a lot smaller. It's a good idea to set this on as a default in your preferences file. tabstospaces "-t#" Tabs to spaces Convert any tabs to spaces. Tabsize used in the textfile is specified in #. # can be from 1 to 16. Without size specification, 8 will be used. mode Mode determines what Port expects the source file to be. Since almost all of the different character codes are used in different textfile formats, it's not easy to know what the format is just by looking what codes are there. So usually you should first take a look at the new textfile and determine what computer it has been written on. Attention! Be careful when choosing your mode, if you choose a wrong mode, you can do irreversible damage to the textfile. Simply using the other mode pair (for example, PC->Amiga & Amiga->PC) will not be able to turn the file back into what it was, since many characters in one character set have no equivalents in other character sets, and those are translated to _similar_ characters. In PC->Amiga mode a PC box character might be translated to a # sign, but when the # sign is converted back to PC, it stays as a # sign. When I made the PC->Amiga and Amiga->PC tables, I always first tried to find an equivalent character. If there was none, I then chose a close match. If there was a character with an accent, but the other format had no such character, I converted the accented character into its un-accented form. If there was an equal character, but in different case, then I translated into that without caring of the case. Since making the table is pretty repetitive work, I'm sure I made some mistakes. I happily change the translations, if you notice a mistake or have a better idea. pctoami "p" PC->Amiga Will strip all characters under $20 except TABs, LFs and ESCs and change all non-ASCII characters ($80-$FF) to the equivalents used on Amiga. Since Amiga's character set differs from the one used in PC, a close match is attempted when no equivalent exists. You should read the information about mode. sf7toami "s" SF7->Amiga Strips all characters under $20 except TABs, LFs and ESCs, and translates the SF7 scands ("[{\|]}") to normal Amiga scands. amitopc "P" Amiga->PC Adds CR's to the end of each line and translates non-ASCII characters to their equivalents on PC. You should read the general information about mode. amitosf7 "S" Amiga->SF7 Strips all characters under $20 except TABs, LFs and ESCs, and translates scands which have an SF7 equivalent to the special SF7 form ("[{\|]}"). lowercase "l" Lowercase Translates all characters to lowercase. IMPORTANT: This is done an Amiga file in mind. So if you try to translate a file of some other type, only the ASCII characters will be changed correctly, many non-ASCII characters will be mangled. uppercase "u" Uppercase Translates all characters to uppercase. IMPORTANT: This is done an Amiga file in mind. So if you try to translate a file of some other type, only the ASCII characters will be changed correctly, many non-ASCII characters will be mangled. onlyasc "o" Only ASCII Cuts all non-ASCII characters (ie. characters with a code higher than $7F), and a lot of characters under $20 from the file. null "n" Null This mode does no conversion, it only strips characters under $20 except TABs, LFs and ESCs. Use this when you want to do special operations, like tab conversion, on an any textfile. source "Source" This is the name of the textfile(s) which you wish to convert. If the file has been PowerPacked, it will be automatically decrunched. You can use wildcards, since Port uses dos.library/MatchNext() to find the files. If you use patterns, you can either specify no destination or the destination must be a directory. Port does not have an "ALL" option, which would convert all files recursively, but this can easily be accomplished by using a couple of a bit more complex patterns. For example, first "Port -s n #?", then "Port -s n #?/#?" and so on. Here's a piece of the documentation for MatchFirst(). The patterns are fairly extensive, and approximate some of the ability of Unix/grep "regular expression" patterns. Here are the available tokens: ? Matches a single character. # Matches the following expression 0 or more times. (ab|cd) Matches any one of the items seperated by '|'. ~ Negates the following expression. It matches all strings that do not match the expression (aka ~(foo) matches all strings that are not exactly "foo"). [abc] Character class: matches any of the characters in the class. [~bc] Character class: matches any of the characters not in the class. a-z Character range (only within character classes). % Matches 0 characters always (useful in "(foo|bar|%)"). * Synonym for "#?", not available by default in 2.0. Available as an option that can be turned on. "Expression" in the above table means either a single character (ex: "#?"), or an alternation (ex: "#(ab|cd|ef)"), or a character class (ex: "#[a-zA-Z]"). dest This is the optional filename or the destination directory for the converted text. This doesn't have to be specified, in that case the original will be overwritten by the converted text. BEWARE! If the new textfile comes out bigger than the original and you run out diskspace, or some other similar error occurs, you will LOSE the file. If you are using the "No conversion buffer" option, the file will not be overwritten. Instead, a new file with the original name and some suffix will be used as the destination instead. misc Aborting the conversion ~~~~~~~~~~~~~~~~~~~~~~~ The conversion can be aborted most of the time by pressing ^C. When using two different files for the source and destination, the conversion can always be aborted. But when converting on the original textfile, the conversion can only be aborted while Port is still reading. After it starts writing, you have to wait until it's finished. This is done to protect the textfile, otherwise everything would be lost. End of conversion ~~~~~~~~~~~~~~~~~ In the end of the conversion, Port shows some information of the converted file compared to the original. The first number tells the change of size in bytes, and the second one the size of the converted file as a percentage of the original. finalwords Port V2.00, based on Port V1.46, was mainly developed between 18-May-94 and 26-Jun-94 in about 90 hours of work. The source code size is currently approximately 4000 lines. Here are some personal hellos to my friends: Axolotl/Capacala Did you have cool time in England and Germany? It will be interesting to see if more people come to Aggressive Party this year (do they have money to set it up anyway?) but it was kind of cool with so few people and so much space. Did alcohol have an effect? Nahh... Breeze/Capacala I'm still quite unsure if I'll code an intro for Ass'94. Maybe, but just maybe. Ged Your new text adventure system is great, it will be very easy and a lot of fun to make adventures for it, when it's finished. Guru Gnosis Sahib Did you say Base? Just a moment, I gotta go to the bathroom, fast! Damn you, code the QWK reader soon, I won't use TIN anymore. Otu Always fun to have around. Hope to see some more cyberpunk stories from you soon! Passy/Capacala Your demo will be cool, but I'm afraid the quality of the PC compo will be TOUGH at Ass'94. I have always thought that coding is clearly an art form. There are so many different ways to do things, some are just plain usual, some are exceedingly witty, and some are damn wicked. Such a shame only another coder can fully appreciate the work at that level. Anyway, I thought about the reasons I coded Port, and why I'm putting it into distribution. It sometimes just felt too good to be given everyone for free. But then I noted that a lot of cool programs I use have been made by other people like me, and they are for free too. I haven't sent money for any of them, though I have often been pretty close to doing so. But then I realized that the proper way to pay back is to code more good stuff since I'm able to do that. I think this is what everyone should do. If you have done some useful code for your own need, why don't you distribute it! Here's a list of coders I think have done nice work: Stefan Boberg - LhA Christoph Feck - FJPEG Holger Kruse - ReOrg Jarno Paananen - S3M code Christophe Passuello - ShowGIF Remember to write if you have some cool suggestions for features you'd like Port to have, or if you happen to find a bug. In case of a bug, tell me exactly what to do to make the bug appear, and send the textfile (or a part of it) which causes the bug, if possible. Also describe it well, if it isn't obvious. And write in any case if you're able; I want to know how many people are using Port! I know it's a pain to write real letters, but everyone can drop a note through Internet. And if you don't have email access, get it! You can get in touch with a lot of people around the world, for free. Why don't people use their modems to their full potential? For my newest programs and Internet email access, call ______ ________/\________/\ /\ \ | /\___ ___/\ /\ /\__ ___ \ /\ /\/ \ \ | /\ \/ / / \ \ \ | | |\ ____/ /\ ____/ /\__/\ |\ |/ |\ _ _ /| /\__/\ |\__ \| | | \/ ___/\ \/ / \| \_/ | \/|\/|\/ |/ \| \ \__ | | / | \ /\ \ | | | | / /\ \ |\ \| |________/|___|\___/ / \ \__|__|___| |__/ / \ \__| \__ \ **[ggs]***********\ /****\ /***************\ /****\ /*******\/* _ \/ \/ \/ \/ -=*=- Sysop: Guru Gnosis Sahib -=*=- Co-Sysops: Shadow Lord & X-Dus -=*=- -=*=- AXsh v1.31 PL1 reg, 68030/25/7MB/320MB & USR 16800 DS -=*=- +358-0-498797 ~~~~~~~~~~~~~ // \X/ Thanks to Amiga for being the coolest computer ever!